https://www.yegor256.com/2018/08/22/builders-and-manipulators.html

Builders and Manipulators

• 22 August 2018
• Palo Alto, CA
• Yegor Bugayenko
• comments

Here is a simple principle for naming methods in OOP, which I’m trying to follow in my code: it’s a verb if it manipulates, it’s a noun if it builds. That’s it. Nothing in between. Methods like saveFile() or getTitle() don’t fit and must be renamed and refactored. Moreover, methods that “manipulate” must always return void, for example print() or save(). Let me explain.

First, I have to say that this idea is very similar to the one suggested by Bertrand Meyer in his book Object Oriented Software Construction, where he proposes we divide an object’s methods into two sharply separated categories: queries and commands.

The idea behind this principle is rather philosophical. Let’s start with builders, which are supposed to create or find an object and then return it. Suppose I have a store of books and I ask it to give me a book by name:

interface Bookshelf {
  Book find(String title);
}

It’s obviously a “builder” (or a “query” in Meyer’s terms). I ask for a book and it’s given to me. The problem, though, is with the name of the method. It’s called “find,” which implies that I know how the book will be dealt with. It will be found.

However, this is not how we should treat our objects. We must not tell them how to do the job we want them to do. Instead, we must let them decide whether the book will be found, constructed, or maybe taken from a memory cache. When we query, we have to say what result we are looking for and let the object make the decision about the way this result is going to be built. A much more appropriate name for this method would be book():

interface Bookshelf {
  Book book(String title);
}

The rule of thumb is: a builder is always a noun. If the method returns something, it has to be a noun. Preferably its name should explain what the method returns. If it’s a book, name it book(). If it’s a file, call the method file(), etc. Here are a few good builder examples:

interface Foo {
  float speed(Actor actor);
  Money salary(User user);
  File database();
  Date deadline(Project project, User user);
}

Here, on the contrary, are a few examples of badly named builders:

interface Foo {
  float calculateSpeed(Actor actor);
  Money getSalary(User user);
  File openDatabase();
  Date readDeadline(Project project, User user);
}

There is no place for a verb in a builder’s name!

It’s not only about the name, by the way. A builder, since its name doesn’t contain a verb, should not do any modifications to the encapsulated entities. It may only create or find something and return it. Just like a pure function, it must not have any side-effects.

Next, there are “manipulators” (or “commands” in Meyer’s terms). They do some work for us, modifying the entities, which the object encapsulates. They are the opposite to builders, because they actually make changes to the world abstracted by the object. For example, we ask the Bookshelf to add a new book to itself:

interface Bookshelf {
  void add(Book book);
}

The method adds the book to the storage. How exactly the storage will be modified, we don’t know. But we know that since the name of the method is a verb, there will be modifications.

Also, manipulators must not return anything. It’s always void that we see as the type of their response. This is needed mostly in order to separate the imperative part of the code from the declarative part. We either receive objects or tell them what to do. We must not mix those activities in one method.

The purpose of these rules is to make the code simpler. If you follow them, and all your builders only return objects and your manipulators only modify the world, the entire design will become easier to understand. Methods will be smaller and their names shorter.

Of course, very often you will have a hard time finding those names. From time to time you will want to return something from a manipulator or make your builder make some changes, say to the cache. Try to resist this temptation and stay with the principle: a method is either a builder or a manipulator, nothing in the middle. The examples above are rather primitive, the code in real life is much more complicated. But that’s what the principle is going to help us with—making the code simpler.

I’m also aware of the noun/verb principle, which suggests always naming classes as nouns and their methods as verbs. I believe it’s a wrong idea, since it doesn’t differentiate builders from manipulators and encourages us to always think in terms of imperative instructions. I believe that OOP must be much more about declarative composition of objects, even if we have to sometimes get them from other objects instead of instantiating them via constructors. That’s why we do need builders in most situations and we also have to see an obvious difference between them and the other methods, manipulators.

You can find a more detailed discussion of this problem in Elegant Objects, Volume 1, Section 2.4.

How would you name a method of a class Document that reads and returns its content? #elegantobjects

— Yegor Bugayenko (@yegor256) August 26, 2018

https://www.yegor256.com/2018/03/27/how-to-test-thread-safety.html

How I Test My Java Classes for Thread-Safety

• 27 March 2018
• Moscow, Russia
• Yegor Bugayenko
• comments

I touched on this problem in one of my recent webinars, now it’s time to explain it in writing. Thread-safety is an important quality of classes in languages/platforms like Java, where we frequently share objects between threads. The issues caused by lack of thread-safety are very difficult to debug, since they are sporadic and almost impossible to reproduce on purpose. How do you test your objects to make sure they are thread-safe? Here is how I’m doing it.

Let us say there is a simple in-memory bookshelf:

class Books {
  final Map<Integer, String> map =
    new ConcurrentHashMap<>();
  int add(String title) {
    final Integer next = this.map.size() + 1;
    this.map.put(next, title);
    return next;
  }
  String title(int id) {
    return this.map.get(id);
  }
}

First, we put a book there and the bookshelf returns its ID. Then we can read the title of the book by its ID:

Books books = new Books();
String title = "Elegant Objects";
int id = books.add(title);
assert books.title(id).equals(title);

The class seems to be thread-safe, since we are using the thread-safe ConcurrentHashMap instead of a more primitive and non-thread-safe HashMap, right? Let’s try to test it:

class BooksTest {
  @Test
  public void addsAndRetrieves() {
    Books books = new Books();
    String title = "Elegant Objects";
    int id = books.add(title);
    assert books.title(id).equals(title);
  }
}

The test passes, but it’s just a one-thread test. Let’s try to do the same manipulation from a few parallel threads (I’m using Hamcrest):

class BooksTest {
  @Test
  public void addsAndRetrieves() {
    Books books = new Books();
    int threads = 10;
    ExecutorService service =
      Executors.newFixedThreadPool(threads);
    Collection<Future<Integer>> futures =
      new ArrayList<>(threads);
    for (int t = 0; t < threads; ++t) {
      final String title = String.format("Book #%d", t);
      futures.add(service.submit(() -> books.add(title)));
    }
    Set<Integer> ids = new HashSet<>();
    for (Future<Integer> f : futures) {
      ids.add(f.get());
    }
    assertThat(ids.size(), equalTo(threads));
  }
}

First, I create a pool of threads via Executors. Then I submit ten objects of type Callable via submit(). Each of them will add a new unique book to the bookshelf. All of them will be executed, in some unpredictable order, by some of those ten threads from the pool.

Then I fetch the results of their executors through the list of objects of type Future. Finally, I calculate the amount of unique book IDs created. If the number is 10, there were no conflicts. I’m using the Set collection in order to make sure the list of IDs contains only unique elements.

The test passes on my laptop. However, it’s not strong enough. The problem here is that it’s not really testing the Books from multiple parallel threads. The time that passes between our calls to submit() is large enough to finish the execution of books.add(). That’s why in reality only one thread will run at the same time. We can check that by modifying the code a bit:

AtomicBoolean running = new AtomicBoolean();
AtomicInteger overlaps = new AtomicInteger();
Collection<Future<Integer>> futures =
  new ArrayList<>(threads);
for (int t = 0; t < threads; ++t) {
  final String title = String.format("Book #%d", t);
  futures.add(
    service.submit(
      () -> {
        if (running.get()) {
          overlaps.incrementAndGet();
        }
        running.set(true);
        int id = books.add(title);
        running.set(false);
        return id;
      }
    )
  );
}
assertThat(overlaps.get(), greaterThan(0));

With this code I’m trying to see how often threads overlap each other and do something in parallel. This never happens and overlaps is equal to zero. Thus our test is not really testing anything yet. It just adds ten books to the bookshelf one by one. If I increase the amount of threads to 1000, they start to overlap sometimes. But we want them to overlap even when there’s a small number of them. To solve that we need to use CountDownLatch:

CountDownLatch latch = new CountDownLatch(1);
AtomicBoolean running = new AtomicBoolean();
AtomicInteger overlaps = new AtomicInteger();
Collection<Future<Integer>> futures =
  new ArrayList<>(threads);
for (int t = 0; t < threads; ++t) {
  final String title = String.format("Book #%d", t);
  futures.add(
    service.submit(
      () -> {
        latch.await();
        if (running.get()) {
          overlaps.incrementAndGet();
        }
        running.set(true);
        int id = books.add(title);
        running.set(false);
        return id;
      }
    )
  );
}
latch.countDown();
Set<Integer> ids = new HashSet<>();
for (Future<Integer> f : futures) {
  ids.add(f.get());
}
assertThat(overlaps.get(), greaterThan(0));

Now each thread, before touching the books, waits for the permission given by latch. When we submit them all via submit() they stay on hold and wait. Then we release the latch with countDown() and they all start to go, simultaneously. Now, on my laptop, overlaps is equal to 3-5 even when threads is 10.

And that last assertThat() crashes now! I’m not getting 10 book IDs, as I was before. It’s 7-9, but never 10. The class, apparently, is not thread-safe!

But before we fix the class, let’s make our test simpler. Let’s use RunInThreads from Cactoos, which does exactly the same as we’ve done above, but under the hood:

class BooksTest {
  @Test
  public void addsAndRetrieves() {
    Books books = new Books();
    MatcherAssert.assertThat(
      t -> {
        String title = String.format(
          "Book #%d", t.getAndIncrement()
        );
        int id = books.add(title);
        return books.title(id).equals(title);
      },
      new RunsInThreads<>(new AtomicInteger(), 10)
    );
  }
}

The first argument of assertThat() is an instance of Func (a functional interface), accepting an AtomicInteger (the first argument of RunsInThreads) and returning Boolean. This function will be executed on 10 parallel thread, using the same latch-based approach as demonstrated above.

This RunInThreads seems to be compact and convenient, I’m using it in a few projects already.

By the way, in order to make Books thread-safe we just need to add synchronized to its method add(). Or maybe you can suggest a better solution?

P.S. I learned all this from Java Concurrency in Practice by Goetz et al.

Do you create unit tests to prove that your classes are thread-safe?

— Yegor Bugayenko (@yegor256) August 12, 2018

https://www.yegor256.com/2018/03/13/fluent-interfaces.html

Fluent Interfaces Are Bad for Maintainability

• 13 March 2018
• Moscow, Russia
• Yegor Bugayenko
• comments

• Discussed at:
• hackernews

Fluent interface, first coined as a term by Martin Fowler, is a very convenient way of communicating with objects in OOP. It makes their facades easier to use and understand. However, it ruins their internal design, making them more difficult to maintain. A few words were said about that by Marco Pivetta in his blog post Fluent Interfaces are Evil; now I will add my few cents.

Let’s take my own library jcabi-http, which I created a few years ago, when I thought that fluent interfaces were a good thing. Here is how you use the library to make an HTTP request and validate its output:

String html = new JdkRequest("https://www.google.com")
  .method("GET")
  .fetch()
  .as(RestResponse.class)
  .assertStatus(200)
  .body();

This convenient method chaining makes the code short and obvious, right? Yes, it does, on the surface. But the internal design of the library’s classes, including JdkRequest, which is the one you see, is very far from being elegant. The biggest problem is that they are rather big and it’s difficult impossible to extend them without making them even bigger.

For example, right now JdkRequest has the methods method(), fetch(), and a few others. What happens when new functionality is required? The only way to add to it would be to make the class bigger, by adding new methods, which is how we jeopardize its maintainability. Here, for example, we added multipartBody() and here we added timeout().

I always feel scared when I get a new feature request in jcabi-http. I understand that it most probably means adding new methods to Request, Response, and other already bloated interfaces and classes.

I actually tried to do something in the library in order to solve this problem but it wasn’t easy. Look at this .as(RestResponse.class) method call. What it does is decorate a Response with RestResponse, in order to make it method-richer. I just didn’t want to make Response contain 50+ methods, like many other libraries do. Here is what it does (this is pseudo-code):

class Response {
  RestResponse as() {
    return new RestResponse(this);
  }
  // Seven methods
}
class RestResponse implements Response {
  private final Response origin;
  // Original seven methods from Response
  // Additional 14 methods
}

As you see, instead of adding all possible methods to Response I placed them in supplementary decorators RestResponse, JsonResponse, XmlResponse, and others. It helps, but in order to write these decorators with the central object of type Response we have to use that “ugly” method as(), which depends heavily on Reflection and type casting.

In other words, fluent interfaces mean large classes or some ugly workarounds. I mentioned this problem earlier, when I wrote about Streams API and the interface Stream, which is perfectly fluent. There are 43 methods!

That is the biggest problem with fluent interfaces—they force objects to be huge.

Fluent interfaces are perfect for their users, since all methods are in one place and the amount of classes is very small. It is easy to use them, especially with code auto-completion in most IDEs. They also make client code more readable, since “fluent” constructs look similar to plain English (aka DSL).

That is all true! However, the damage they cause to object design is the price, which is too high.

What is the alternative?

I would recommend you use decorators and smart objects instead. Here is how I would design jcabi-http, if I could do it now:

String html = new BodyOfResponse(
  new ResponseAssertStatus(
    new RequestWithMethod(
      new JdkRequest("https://www.google.com"),
      "GET"
    ),
    200
  )
).toString();

This is the same code as in the first snippet above, but it is much more object-oriented. The obvious problem with this code, of course, is that the IDE won’t be able to auto-complete almost anything. Also, we will have to remember many of the names of the classes. And the construct looks rather difficult to read for those who are used to fluent interfaces. In addition, it’s very far away from the DSL idea.

But here is the list of benefits. First, each object is small, very cohesive and they are all loosely coupled—which are obvious merits in OOP. Second, adding new functionality to the library is as easy as creating a new class; no need to touch existing classes. Third, unit testing is simplified, since classes are small. Fourth, all classes can be immutable, which is also an obvious merit in OOP.

Thus, there seems to be a conflict between usefulness and maintainability. Fluent interfaces are good for users, but bad for library developers. Small objects are good for developers, but difficult to understand and use.

It seems to be so, but only if you are used to large classes and procedural programming. To me, a large amount of small classes seems to be an advantage, not a drawback. Libraries that are clear, simple, and readable inside are much easier to use, even when I don’t know exactly which classes out there are the most suitable for me. Even without the code-auto-complete I can figure it out myself, because the code is clean.

Also, I very often find myself interested in extending existing functionality either inside my code base or via a pull request to the library. I am much more interested to do that if I know that the changes I introduce are isolated and easy to test.

Thus, no fluent interfaces anymore from me, only objects and decorators.

https://www.yegor256.com/2018/02/27/parsing-objects.html

Don't Parse, Use Parsing Objects

• 27 February 2018
• Moscow, Russia
• Yegor Bugayenko
• comments

The traditional way of integrating object-oriented back-end with an external system is through data transfer objects, which are serialized into JSON before going out and deserialized when coming back. This way is as much popular as it is wrong. The serialization part should be replaced by printers, which I explained earlier. Here is my take on deserialization, which should be done by—guess what—objects.

Say there is a back-end entry point, which is supposed to register a new book in the library, arriving in JSON:

{
  "title": "Object Thinking",
  "isbn: "0735619654",
  "author: "David West"
}

Also, there is an object of class Library, which expects an object of type Book to be given to its method register():

class Library {
  public void register(Book book) {
    // Create a new record in the database
  }
}

Say also, type Book has a simple method isbn():

interface Book {
  String isbn();
}

Now, here is the HTTP entry point (I’m using Takes and Cactoos), which is accepting a POST multipart/form-data request and registering the book in the library:

public class TkUpload implements Take {
  private final Library library;
  @Override
  public Response act(Request req) {
    String body = new RqPrint(
      new RqMtSmart(new RqMtBase(req)).single("book")
    ).printBody();
    JsonObject json = Json.createReader(
      new InputStreamOf(body)
    ).readObject();
    Book book = new BookDTO();
    book.setIsbn(json.getString("isbn"));
    library.register(book);
  }
}

What is wrong with this? Well, a few things.

First, it’s not reusable. If we were to need something similar in a different place, we would have to write this HTTP processing and JSON parsing again.

Second, error handling and validation are not reusable either. If we add it to the method above, we will have to copy it everywhere. Of course, the DTO may encapsulate it, but that’s not what DTOs are usually for.

Third, the code above is rather procedural and has a lot of temporal coupling.

A better design would be to hide this parsing inside a new class JsonBook:

class JsonBook implements Book {
  private final String json;
  JsonBook(String body) {
    this.json = body;
  }
  @Override
  public String isbn() {
    return Json.createReader(
      new InputStreamOf(body)
    ).readObject().getString("isbn");
  }
}

Then, the RESTful entry point will look like this:

public class TkUpload implements Take {
  private final Library library;
  @Override
  public Response act(Request req) {
    library.register(
      new JsonBook(
        new RqPrint(
          new RqMtSmart(
            new RqMtBase(req)
          ).single("book")
        ).printBody()
      )
    );
  }
}

Isn’t that more elegant?

Here are some examples from my projects: RqUser from zerocracy/farm and RqUser from yegor256/jare.

As you can see from the examples above, sometimes we can’t use implements because some primitives in Java are not interfaces but final classes: String is a “perfect” example. That’s why I have to do this:

class RqUser implements Scalar<String> {
  @Override
  public String value() {
    // Parsing happens here and returns String
  }
}

But aside from that, these examples perfectly demonstrate the principle of “parsing objects” suggested above.

https://www.yegor256.com/2017/12/12/alan-kay-was-wrong.html

Alan Kay Was Wrong About Him Being Wrong

• 12 December 2017
• Moscow, Russia
• Yegor Bugayenko
• comments

From time to time someone asks me what I think about what Alan Kay, the father of OOP, the designer of Smalltalk, the first object-oriented language, said in 1998 about OOP. He literally said that the very term “object” was misleading and a more appropriate one would be “messaging.” Here is what I think.

I believe that there are two orthogonal means of interaction between objects: messaging and composition. Let’s say, we have a point and a canvas:

Point p = new Point(x, y);
Canvas canvas = new Canvas();

This is how messaging would look:

p.printTo(canvas);

The problem with messaging is that it keeps objects on the same level of abstraction. They communicate as equal and independent “modules,” sending data messages to each other. Even though they look object-oriented, the entire communication pattern is very procedural. We try to encapsulate as much as we can inside a single object, however inevitably still having to expose a lot of its data in order to be able to “connect” it with other objects.

We turn objects into “little computers,” as some books refer to them. They expect data to come in, they process the data, and return back some new data. The maintainability problem is not really solved with this approach—we still have to deal with a lot of data, remembering its semantic outside of the objects. In other words, there is no true encapsulation.

On the other hand, this is how composition would look instead:

Point p2 = new PrintedOn(p, canvas);

Every time we need objects to communicate we create a bigger object that encapsulates more primitive ones, letting them interact inside. Of course, the data will also go from object to object, but that will happen inside a bigger object. We can even make the encapsulator and the encapsulated “friends,” as I suggested before, to make that interaction more transparent and avoid data exposure through getters or even printers.

Let me quote Alan Kay again:

The key in making great and growable systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be.

It seems to me that he means modules, which are not objects. These are different things. Modules are elements of the architecture, while objects are elements of the design. These are two different levels. At the level of architecture we obviously need messages and Kay’s statement is perfectly correct. However, at the level of design we need composable structures, to increase maintainability and messaging is not what can help us achieve this goal.

Thus, I believe Alan Kay was right when he invented objects, called them objects, and gave their programming style the “object-oriented” title.

https://www.yegor256.com/2017/11/14/static-factory-methods.html

Constructors or Static Factory Methods?

• 14 November 2017
• Odessa, Ukraine
• Yegor Bugayenko
• comments

• Discussed at:
• dzone

I believe Joshua Bloch said it first in his very good book “Effective Java”: static factory methods are the preferred way to instantiate objects compared with constructors. I disagree. Not only because I believe that static methods are pure evil, but mostly because in this particular case they pretend to be good and make us think that we have to love them.

Let’s analyze the reasoning and see why it’s wrong, from an object-oriented point of view.

This is a class with one primary and two secondary constructors:

class Color {
  private final int hex;
  Color(String rgb) {
    this(Integer.parseInt(rgb, 16));
  }
  Color(int red, int green, int blue) {
    this(red << 16 + green << 8 + blue);
  }
  Color(int h) {
    this.hex = h;
  }
}

This is a similar class with three static factory methods:

class Color {
  private final int hex;
  static Color makeFromRGB(String rgb) {
    return new Color(Integer.parseInt(rgb, 16));
  }
  static Color makeFromPalette(int red, int green, int blue) {
    return new Color(red << 16 + green << 8 + blue);
  }
  static Color makeFromHex(int h) {
    return new Color(h);
  }
  private Color(int h) {
    this.hex = h;
  }
}

Which one do you like better?

According to Joshua Bloch, there are three basic advantages to using static factory methods instead of constructors (there are actually four, but the fourth one is not applicable to Java anymore):

• They have names.
• They can cache.
• They can subtype.

I believe that all three make perfect sense … if the design is wrong. They are good excuses for workarounds. Let’s take them one by one.

They Have Names

This is how you make a red tomato color object with a constructor:

Color tomato = new Color(255, 99, 71);

This is how you do it with a static factory method:

Color tomato = Color.makeFromPalette(255, 99, 71);

It seems that makeFromPalette() is semantically richer than just new Color(), right? Well, yes. Who knows what those three numbers mean if we just pass them to the constructor. But the word “palette” helps us figure everything out immediately.

True.

However, the right solution would be to use polymorphism and encapsulation, to decompose the problem into a few semantically rich classes:

interface Color {
}
class HexColor implements Color {
  private final int hex;
  HexColor(int h) {
    this.hex = h;
  }
}
class RGBColor implements Color {
  private final Color origin;
  RGBColor(int red, int green, int blue) {
    this.origin = new HexColor(
      red << 16 + green << 8 + blue
    );
  }
}

Now, we use the right constructor of the right class:

Color tomato = new RGBColor(255, 99, 71);

See, Joshua?

They Can Cache

Let’s say I need a red tomato color in multiple places in the application:

Color tomato = new Color(255, 99, 71);
// ... sometime later
Color red = new Color(255, 99, 71);

Two objects will be created, which is obviously inefficient, since they are identical. It would be better to keep the first instance somewhere in memory and return it when the second call arrives. Static factory methods make it possible to solve this very problem:

Color tomato = Color.makeFromPalette(255, 99, 71);
// ... sometime later
Color red = Color.makeFromPalette(255, 99, 71);

Then somewhere inside the Color we keep a private static Map with all the objects already instantiated:

class Color {
  private static final Map<Integer, Color> CACHE =
    new HashMap<>();
  private final int hex;
  static Color makeFromPalette(int red, int green, int blue) {
    final int hex = red << 16 + green << 8 + blue;
    return Color.CACHE.computeIfAbsent(
      hex, h -> new Color(h)
    );
  }
  private Color(int h) {
    return new Color(h);
  }
}

It is very effective performance-wise. With a small object like our Color the problem may not be so obvious, but when objects are bigger, their instantiation and garbage collection may waste a lot of time.

True.

However, there is an object-oriented way to solve this problem. We just introduce a new class Palette, which becomes a store of colors:

class Palette {
  private final Map<Integer, Color> colors =
    new HashMap<>();
  Color take(int red, int green, int blue) {
    final int hex = red << 16 + green << 8 + blue;
    return this.computerIfAbsent(
      hex, h -> new Color(h)
    );
  }
}

Now, we make an instance of Palette once and ask it to return a color to us every time we need it:

Color tomato = palette.take(255, 99, 71);
// Later we will get the same instance:
Color red = palette.take(255, 99, 71);

See, Joshua, no static methods, no static attributes.

They Can Subtype

Let’s say our class Color has a method lighter(), which is supposed to shift the color to the next available lighter one:

class Color {
  protected final int hex;
  Color(int h) {
    this.hex = h;
  }
  public Color lighter() {
    return new Color(hex + 0x111);
  }
}

However, sometimes it’s more desirable to pick the next lighter color through a set of available Pantone colors:

class PantoneColor extends Color {
  private final PantoneName pantone;
  PantoneColor(String name) {
    this(new PantoneName(name));
  }
  PantoneColor(PantoneName name) {
    this.pantone = name;
  }
  @Override
  public Color lighter() {
    return new PantoneColor(this.pantone.up());
  }
}

Then, we create a static factory method, which will decide which Color implementation is the most suitable for us:

class Color {
  private final String code;
  static Color make(int h) {
    if (h == 0xBF1932) {
      return new PantoneColor("19-1664 TPX");
    }
    return new RGBColor(h);
  }
}

If the true red color is requested, we return an instance of PantoneColor. In all other cases it’s just a standard RGBColor. The decision is made by the static factory method. This is how we will call it:

Color color = Color.make(0xBF1932);

It would not be possible to do the same “forking” with a constructor, since it can only return the class it is declared in. A static method has all the necessary freedom to return any subtype of Color.

True.

However, in an object-oriented world we can and must do it all differently. First, we would make Color an interface:

interface Color {
  Color lighter();
}

Next, we would move this decision making process to its own class Colors, just like we did in the previous example:

class Colors {
  Color make(int h) {
    if (h == 0xBF1932) {
      return new PantoneColor("19-1664-TPX");
    }
    return new RGBColor(h);
  }
}

And we would use an instance of class Colors instead of a static faсtory method inside Color:

colors.make(0xBF1932);

However, this is still not really an object-oriented way of thinking, because we’re taking the decision-making away from the object it belongs to. Either through a static factory method make() or a new class Colors—it doesn’t really matter how—we tear our objects into two pieces. The first piece is the object itself and the second one is the decision making algorithm that stays somewhere else.

A much more object-oriented design would be to put the logic into an object of class PantoneColor which would decorate the original RGBColor:

class PantoneColor {
  private final Color origin;
  PantoneColor(Color color) {
    this.origin = color;
  }
  @Override
  public Color lighter() {
    final Color next;
    if (this.origin.hex() == 0xBF1932) {
      next = new RGBColor(0xD12631);
    } else {
      next = this.origin.lighter();
    }
    return new PantoneColor(next);
  }
)

Then, we make an instance of RGBColor and decorate it with PantoneColor:

Color red = new PantoneColor(
  new RGBColor(0xBF1932)
);

We ask red to return a lighter color and it returns the one from the Pantone palette, not the one that is merely lighter in RGB coordinates:

Color lighter = red.lighter(); // 0xD12631

Of course, this example is rather primitive and needs further improvement if we really want it to be applicable to all Pantone colors, but I hope you get the idea. The logic must stay inside the class, not somewhere outside, not in static factory methods or even in some other supplementary class. I’m talking about the logic that belongs to this particular class, of course. If it’s something related to the management of class instances, then there can be containers and stores, just like in the previous example above.

To summarize, I would strongly recommend you never use static methods, especially when they are going to replace object constructors. Giving birth to an object through its constructor is the most “sacred” moment in any object-oriented software, don’t miss the beauty of it.

https://www.yegor256.com/2017/11/07/five-new-java-features.html

Five Features to Make Java Even Better

• 7 November 2017
• Odessa, Ukraine
• Yegor Bugayenko
• comments

• Discussed at:
• dzone

I stumbled upon this proposal by Brian Goetz for data classes in Java, and immediately realized that I too have a few ideas about how to make Java better as a language. I actually have many of them, but this is a short list of the five most important.

Global Variables. There are Singletons in Java, which, as we all know, are nothing but global variables. Wouldn’t it be great to enable global variables in Java and get rid of Singletons. PHP, JavaScript, Ruby and many other languages have them, why doesn’t Java? Look at this code:

class User {
  private static User INSTANCE;
  private User() {}
  public static User getInstance() {
    synchronized (User.INSTANCE) {
      if (User.INSTANCE == null) {
        User.INSTANCE = new User();
      }
    }
    return User.INSTANCE;
  }
  public String getName() {
    // return user's name
  }
}

Then, to access it we have to use:

String name = User.getInstance().getName();

This is a Singleton. See how verbose it is? We can simply replace it with a global variable (global is the keyword I’m suggesting we use):

global User user;

And then:

user.getName();

Much less code to write, and way easier to read!

Global Functions and Namespaces

To group static methods together we create utility classes, where we have to define private constructors to prevent their instantiation. Also, we have to remember which particular utility class a static method is in. It’s just extra hassle. I’m suggesting we add global functions to Java and optional “namespaces” to group them. Take a look at this utility class:

class TextUtils {
  private TextUtils() {}
  public static String trim(String text) {
    if (text == null) {
      return "";
    }
    return text.trim();
  }
}

Now look at this global function with a namespace:

namespace TextUtils {
  String trim(String text) {
    if (text == null) {
      return "";
    }
    return text.trim();
  }
}

My point is that since we are already using classes as collections of functions, let’s make it more convenient. In some applications we won’t even need namespaces, just global functions, like in C and C++.

Full Access to Private Attributes and Methods

In order to access a private attribute or a method of an object from outside we have to use the Reflection API. It’s not particularly difficult, but it does take a few lines of code, which are not so easy to read and understand:

class Point {
  private int x;
  private int y;
}
Point point = new Point();
Field field = point.getClass().getDeclaredField("x");
field.setAccessible(true);
int x = (int) field.get(point);

I’m suggesting we allow any object to access any of the attributes and methods of another object:

Point point = new Point();
int x = point.x;

Of course, if they are private, the compiler will issue a warning. At compile time you simply ignore the warning and move on. If you really care about encapsulation, pay attention to the warning and do something else. But in most cases programmers will ignore it, since they would happily use the Reflection API anyway.

NULL by Default

It would be convenient to let us call constructors and methods with an incomplete set of arguments. The arguments we don’t provide will be set to null by default. Also, when a method has to return something, but there is no return statement, Java should return null. This is almost exactly how it works in PHP, Ruby, and many other languages. I believe it would be a convenient feature for Java monkeys developers too.

We won’t need to define so many methods when some of the arguments are optional. Method overloading is very verbose and difficult to understand. Instead, we should have one method with a long list of arguments. Some of them will be provided by the caller, others will be set to null. The method will decide what to do, for example:

void save(File file, String encoding) {
 if (encoding == null) {
   encoding = "UTF-8";
 }
}

Then we just call either save(f) or save(f, "UTF-16"). The method will understand what we mean. We can also make it even more convenient, like it’s done in Ruby, providing method arguments by names:

save(file: f, encoding: "UTF-16");

Also, when there is nothing to return, the method must return null by default. Writing return null is just a waste of a code line and doesn’t really improve readability. Take a look:

String load(File file) {
 if (file.exists()) {
   return read_the_content();
 }
}

It’s obvious from this code that if the file exists, the method loads and returns its content. If not, it returns null, which will be a good indicator for the caller that something is not right and the content of the file is not available.

Getters and Setters

I think it’s only obvious that we need this feature: every private attribute must automatically have a setter and a getter. There should be no need to create them, Java will provide them out-of-the-box, just like Kotlin and Ruby do. What is the point of having an attribute if there are no getters and setters to read it and to modify it, right?

With this new feature we’ll no longer need the help of Lombok, or IntelliJ IDEA.

Maybe I should turn my ideas into official proposals to JCP. What do you think?

https://www.yegor256.com/2017/10/17/lazy-loading-caching-sticky-cactoos.html

Lazy Loading and Caching via Sticky Cactoos Primitives

• 17 October 2017
• Odessa, Ukraine
• Yegor Bugayenko
• comments

You obviously know what lazy loading is, right? And you no doubt know about caching. To my knowledge, there is no elegant way in Java to implement either of them. Here is what I found out for myself with the help of Cactoos primitives.

Let’s say we need an object that will encrypt some text. Speaking in a more object-oriented way, it will encapsulate the text and become its encrypted form. Here is how we will use it (let’s create tests first):

interface Encrypted {
  String asString() throws IOException;
}
Encrypted enc = new EncryptedX("Hello, world!");
System.out.println(enc.asString());

Now let’s implement it, in a very primitive way, with one primary constructor. The encryption mechanism will just add +1 to each byte in the incoming data, and will assume that the encryption won’t break anything (a very stupid assumption, but for the sake of this example it will work):

class Encrypted1 implements Encrypted {
  private final String text;
  Encrypted1(String txt) {
    this.text = txt;
  }
  @Override
  public String asString() {
    final byte[] in = this.text.getBytes();
    final byte[] out = new byte[in.length];
    for (int i = 0; i < in.length; ++i) {
      out[i] = (byte) (in[i] + 1);
    }
    return new String(out);
  }
}

Looks correct so far? I tested it and it works. If the input is "Hello, world!", the output will be "Ifmmp-!xpsme\"".

Next, let’s say that we want our class to accept an InputStream as well as a String. We want to call it like this, for example:

Encrypted enc = new Encrypted2(
  new FileInputStream("/tmp/hello.txt")
);
System.out.println(enc.toString());

Here is the most obvious implementation, with two primary constructors (again, the implementation is primitive, but works):

class Encrypted2 implements Encrypted {
  private final String text;
  Encrypted2(InputStream input) throws IOException {
    ByteArrayOutputStream baos =
      new ByteArrayOutputStream();
    while (true) {
      int one = input.read();
      if (one < 0) {
        break;
      }
      baos.write(one);
    }
    this.text = new String(baos.toByteArray());
  }
  Encrypted2(String txt) {
    this.text = txt;
  }
  // asString() is exactly the same as in Encrypted1
}

Technically it works, but stream reading is right inside the constructor, which is bad practice. Primary constructors must not do anything but attribute assignments, while secondary ones may only create new objects.

Let’s try to refactor and introduce lazy loading:

class Encrypted3 implements Encrypted {
  private String text;
  private final InputStream input;
  Encrypted3(InputStream stream) {
    this.text = null;
    this.input = stream;
  }
  Encrypted3(String txt) {
    this.text = txt;
    this.input = null;
  }
  @Override
  public String asString() throws IOException {
    if (this.text == null) {
      ByteArrayOutputStream baos =
        new ByteArrayOutputStream();
      while (true) {
        int one = input.read();
        if (one < 0) {
          break;
        }
        baos.write(one);
      }
      this.text = new String(baos.toByteArray());
    }
    final byte[] in = this.text.getBytes();
    final byte[] out = new byte[in.length];
    for (int i = 0; i < in.length; ++i) {
      out[i] = (byte) (in[i] + 1);
    }
    return new String(out);
  }
}

Works great, but looks ugly. The ugliest part is these two lines of course:

this.text = null;
this.input = null;

They make the object mutable and they’re using NULL. It’s ugly, trust me. Unfortunately, lazy loading and NULL references always come together in classic examples. However there is a better way to implement it. Let’s refactor our class, this time using Scalar from Cactoos:

class Encrypted4 implements Encrypted {
  private final IoCheckedScalar<String> text;
  Encrypted4(InputStream stream) {
    this(
      () -> {
        ByteArrayOutputStream baos =
          new ByteArrayOutputStream();
        while (true) {
          int one = stream.read();
          if (one < 0) {
            break;
          }
          baos.write(one);
        }
        return new String(baos.toByteArray());
      }
    );
  }
  Encrypted4(String txt) {
    this(() -> txt);
  }
  Encrypted4(Scalar<String> source) {
    this.text = new IoCheckedScalar<>(source);
  }
  @Override
  public String asString() throws IOException {
    final byte[] in = this.text.value().getBytes();
    final byte[] out = new byte[in.length];
    for (int i = 0; i < in.length; ++i) {
      out[i] = (byte) (in[i] + 1);
    }
    return new String(out);
  }

Now it looks way better. First of all, there is only one primary constructor and two secondary ones. Second, the object is immutable. Third, there is still a lot of room for improvement: we can add more constructors which will accept other sources of data, for example File or a byte array.

In a nutshell, the attribute that is supposed to be loaded in a “lazy” way is represented inside an object as a “function” (lambda expression in Java 8). Until we touch that attribute, it’s not loaded. Once we need to work with it, the function gets executed and we have the result.

There is one problem with this code though. It will read the input stream every time we call asString(), which will obviously not work, since only the first time will the stream have the data. On every subsequent call the stream will simply be empty. Thus, we need to make sure that this.text.value() executes the encapsulated Scalar only once. All later calls must return the previously calculated value. So we need to cache it. Here is how:

class Encrypted5 implements Encrypted {
  private final IoCheckedScalar<String> text;
  // same as above in Encrypted4
  Encrypted5(Scalar<String> source) {
    this.text = new IoCheckedScalar<>(
      new StickyScalar<>(source)
    );
  }
  // same as above in Encrypted4

This StickyScalar will make sure that only the first call to its method value() will go through to the encapsulated Scalar. All other calls will receive the result of the first call.

The last problem to solve is about concurrency. The code we have above is not thread safe. If I create an instance of Encrypted5 and pass it to two threads, which call asString() simultaneously, the result will be unpredictable, simply because StickyScalar is not thread-safe. There is another primitive to help us out though, called SyncScalar:

class Encrypted5 implements Encrypted {
  private final IoCheckedScalar<String> text;
  // same as above in Encrypted4
  Encrypted5(Scalar<String> source) {
    this.text = new IoCheckedScalar<>(
      new SyncScalar<>(
        new StickyScalar<>(source)
      )
    );
  }
  // same as above in Encrypted4

Now we’re safe and the design is elegant. It includes lazy loading and caching.

I’m using this approach in many projects now and it seems convenient, clear, and object-oriented.

https://www.yegor256.com/2017/10/10/streams-vs-decorators.html

Streams vs. Decorators

• 10 October 2017
• Odessa, Ukraine
• Yegor Bugayenko
• comments

• Discussed at:
• dzone

The Streams API was introduced in Java 8, together with lambda expressions, just a few years ago. I, as a disciplined Java adept, tried to use this new feature in a few of my projects, for example here and here. I didn’t really like it and went back to good old decorators. Moreover, I created Cactoos, a library of decorators, to replace Guava, which is not so good in so many places.

Here is a primitive example. Let’s say we have a collection of measurements coming in from some data source, they are all numbers between zero and one:

Iterable<Double> probes;

Now, we need to show only the first 10 of them, ignoring zeros and ones, and re-scaling them to (0..100). Sounds like an easy task, right? There are three ways to do it: procedural, object-oriented, and the Java 8 way. Let’s start with the procedural way:

int pos = 0;
for (Double probe : probes) {
  if (probe == 0.0d || probe == 1.0d) {
    continue;
  }
  if (++pos > 10) {
    break;
  }
  System.out.printf(
    "Probe #%d: %f", pos, probe * 100.0d
  );
}

Why is this a procedural way? Because it’s imperative. Why is it imperative? Because it’s procedural. Nah, I’m kidding.

It’s imperative because we’re giving instructions to the computer about what data to put where and how to iterate through it. We’re not declaring the result, but imperatively building it. It works, but it’s not really scalable. We can’t take part of this algorithm and apply it to another use case. We can’t really modify it easily, for example to take numbers from two sources instead of one, etc. It’s procedural. Enough said. Don’t do it this way.

Now, Java 8 gives us the Streams API, which is supposed to offer a functional way to do the same. Let’s try to use it.

First, we need to create an instance of Stream, which Iterable doesn’t let us obtain directly. Then we use the stream API to do the job:

StreamSupport.stream(probes.spliterator(), false)
  .filter(p -> p == 0.0d || p == 1.0d)
  .limit(10L)
  .forEach(
    probe -> System.out.printf(
      "Probe #%d: %f", 0, probe * 100.0d
    )
  );

This will work, but will say Probe #0 for all probes, because forEach() doesn’t work with indexes. There is no such thing as forEachWithIndex() in the Stream interface as of Java 8 (and Java 9 too). Here is a workaround with an atomic counter:

AtomicInteger index = new AtomicInteger();
StreamSupport.stream(probes.spliterator(), false)
  .filter(probe -> probe != 0.0d && probe != 1.0d)
  .limit(10L)
  .forEach(
    probe -> System.out.printf(
      "Probe #%d: %f",
      index.getAndIncrement(),
      probe * 100.0d
    )
  );

“What’s wrong with that?” you may ask. First, see how easily we got into trouble when we didn’t find the right method in the Stream interface. We immediately fell off the “streaming” paradigm and got back to the good old procedural global variable (the counter). Second, we don’t really see what’s going on inside those filter(), limit(), and forEach() methods. How exactly do they work? The documentation says that this approach is “declarative” and each method in the Stream interface returns an instance of some class. What classes are they? We have no idea by just looking at this code.

These two problems are connected. The biggest issue with this streaming API is the very interface Stream—it’s huge. At the time of writing there are 43 methods. Forty three, in a single interface! This is against each and every principle of object-oriented programming, starting with SOLID and then up to more serious ones.

What is the object-oriented way to implement the same algorithm? Here is how I would do it with Cactoos, which is just a collection of primitive simple Java classes:

new And(
  new Mapped<Double, Scalar<Boolean>>(
    new Limited<Double>(
      new Filtered<Double>(
        probes,
        probe -> probe != 0.0d && probe != 1.0d
      ),
      10
    ),
    probe -> () -> {
      System.out.printf(
        "Probe #%d: %f", 0, probe * 100.0d
      );
      return true;
    }
  )
).value();

Let’s see what’s going on here. First, Filtered decorates our iterable probes to take certain items out of it. Notice that Filtered implements Iterable. Then Limited, also being an Iterable, takes only the first ten items out. Then Mapped converts each probe into an instance of Scalar<Boolean>, which does the line printing.

Finally, the instance of And goes through the list of “scalars” and ask each of them to return boolean. They print the line and return true. Since it’s true, And makes the next attempt with the next scalar. Finally, its method value() returns true.

But wait, there are no indexes. Let’s add them. In order to do that we just use another class, called AndWithIndex:

new AndWithIndex(
  new Mapped<Double, Func<Integer, Boolean>>(
    new Limited<Double>(
      new Filtered<Double>(
        probes,
        probe -> probe != 0.0d && probe != 1.0d
      ),
      10
    ),
    probe -> index -> {
      System.out.printf(
        "Probe #%d: %f", index, probe * 100.0d
      );
      return true;
    }
  )
).value();

Instead of Scalar<Boolean> we now map our probes to Func<Integer, Boolean> to let them accept the index.

The beauty of this approach is that all classes and interfaces are small and that’s why they’re very composable. To make an iterable of probes limited we decorate it with Limited; to make it filtered we decorate it with Filtered; to do something else we create a new decorator and use it. We’re not stuck to one single interface like Stream.

The bottom line is that decorators are an object-oriented instrument to modify the behavior of collections, while streams is something else which I can’t even find the name for.

P.S. By the way, this is how the same algorithm can be implemented with the help of Guava’s Iterables:

Iterable<Double> ready = Iterables.limit(
  Iterables.filter(
    probes,
    probe -> probe != 0.0d && probe != 1.0d
  ),
  10
);
int pos = 0;
for (Double probe : probes) {
  System.out.printf(
    "Probe #%d: %f", pos++, probe * 100.0d
  );
}

This is some weird combination of object-oriented and functional styles.